Graphics Plus/Graphics Plus.iso/msdos/editors/bcut/bcut.doc

Text File | 1993-08-31 | 12.5 KB | 396 lines

            PCX Brush Cutter
              Version 1.0
               Vu Nguyen



INTRODUCTION:

This is a brush cutting program for programmers that need a program that reads
PCX image file and clipps brushes and saves them to a simple raw format.
I don't know about anybody else but when i was searching for something like
this on the net, nothing like it existed; so, i decided to write one and
release it to the public domain hoping it will help some other unfortunate
soul. I also included a command line conversion program (called pcx2raw.exe
and pcxpal.exe) to convert a given PCX image file to my own raw format and
to extract the palette in a PCX file.



SOFTWARE AGREEMENT:

This is freeway so give it to whoever/whomever wants it. There should be no
charge for this software except in the case of distribution. In such cases the
cost should only be for media only.  If you think i did a good job and
deserve to be rewarded, then send the money to your favorite charity or to
the 386 bsd development group. Of course this excludes regarding yourself as
your own favority charity organization. Have fun and enjoy.


CONTENTS:

When you unzip the bcut.zip file you should get the following...

BCUT     EXE    102222 08-29-93   7:49p
STD      FNT      3950 12-07-92   3:55p
PCX2RAW  EXE     33266 07-25-93  10:50p
PCXPAL   EXE     33042 07-26-93   7:34p
BCUT     DOC     12824 08-31-93   1:38p
        8 file(s)     185061 bytes



SYSTEM REQUIREMENTS:

The only requirements for this program is that you use a 386 or better, a VGA
display adapter, have plenty of memory, and a mouse. bcut was written in
protected mode so anything less than a 386 won't work. as for the memory
requirements, the more memory you have the better it works. Rather, the more
brush you can cut and the more PCX pictures you can display. About the mouse,
i have to say sorry to the people that don't have one. it's just simply too
difficult to do something like brush cutting without a mouse. I guess now is
a good time to consider buying a one.  One other thing, the PCX files are
assumed to be 256 color PCX files. Anything else won't work.



STD.FNT FILE:

This is the font file used by bcut. without this you won't be able to read
anything you type because nothing will come up on the screen. Make sure this
file resides at the root of your C drive.



COMMAND LINE:

You can load multiple file in bcut when you use the program by typing...

    bcut file1.pcx file2.pcx file3.pcx

This will load all three file into the three different buffers. and you can
change around by using the F1 and F2 keys. Look at the next section for more
details.



KEYBOARD AND MOUSE USAGE:

At one point i was going to put a menu system in for this program but decided
against it because it takes too long to select a menu item. Instead i decided
to use the keyboard and mouse together. The key strokes are shown below.

    IN CUTTING MODE:

        a/A - Add current brush to a brush list. The brush's
              offset can later be modified in the offset
              modification part of bcut.

        b/B - Start the cutting process. After pressing this
              button you should see a cross hair. The by pressing
              the LMB (Left Mouse Button) the cross hair will
              change to a selection box. Now move the mouse to the
              desired area and press the LMB again. The region will
              then be clipped out and appear as the mouse cursor.
              If you have made a mistake and wish to cancel the
              current region, just press the RMB (Right Mouse Button)
              and the operation will be aborted.

        h/H - The online help menu

        l/L - Load new PCX file. Sorry, you have to type in the
              file name. maybe i'll put in a mouse selection deal
              in the future.

        m/M - Modify the offset of the brushes in the brush list.
              Note that each buffer contains different brush lists.

        p/P - Pick a brush from the brush list. This is useful
              if you decide to save only one brush instead of a
              list of brushes. When picking a brush you can use
              the n/N key for the next brush and the p/P key for
              the previous brush. To accept the brush you can press
              either RETURN/SPACE.

        q/Q - quit

        r   - Load an individual brush. I normally call the single
              brush file [filename].raw to distinguish from the
              brush list files, which i call [filename].pck. you,
              however, can decide to call what ever you like but
              becareful not to load a single brush file as a packed
              brush file. The results will be unpredictable.

        R   - Load a packed brush file for the current PCX image
              buffer. If there were brushed when this operation is
              executed, the other brushes will be erase.

        s/S - Save current brush as a single brush file. You must
              either pick a brush from the brush list or clipped
              a region before executing this key stroke.

        z/Z - This will clear out the current brush list.

        PgUp/PgDn - This will lighten or darken the color of
                the background so that brushes can be seen
                easily.

        Home - This will reset the image so that the image's
               upper left hand corner will correspond with the
               screen's upper left hand corner.

        Arrow UP/DOWN/LEFT/RIGHT - This will scroll the image
                       around if you image is bigger
                       than 320x200.

        F1  - Will go to the next buffer. Currently there are only
              3 buffers and you can switch around by using this key
              and the F2 key.

        F2  - Previous buffer.

        .   - This will clear the current brush. Pressing the RMB
              will perform the same action.



    IN MODIFYING BRUSH OFFSET MODE:

        Arrow UP/DOWN/LEFT/RIGHT - This will change the current
                       brush's offset. You should be
                       able to see the brush change
                       position relative to the brush's
                       origin.

        c/C - Clears the current brush list and returns to the
              brush cutting mode.

        d/D - Delete current brush from brush list. If the current
              brush is the last brush in the list, bcut will
              automatically switch back to brush cutting mode.

        f/F - Save the current brush list as a raw bitmap font
              format. There has to be a total of 94 brushes with
              the same width and height in order for this operation
              to work. This command assumes that the first brush
              represents the '!' character and the last brush is
              the '~' character. refer to an ascii table and you
              will see the range of characters. This is my own
              hoaky font format for when i need graphical fonts in
              my program. The file format is shown in the FILE FORMAT
              section.

        h/H - The online help menu.

        l/L - Load a packed brush file. This operation will erase
              all existing brush in the brush list.

        m/M - This operation will append a packed brush list to
              the current brush list.

        n/N - Next brush.

        p/P - Previous brush.

        q/Q/ESC - Quit and return to brush cutting mode.

        s/S - save the current brush list as a packed brush format.

        LMB - This will alter the brush's offset just like the
              arrow keys except much faster.

        RMB - This will move the brush's origin to a different
              location.

        Home - This will reset the origin to the center of the screen.



FILE FORMAT:

The file format are as follows:

    Raw format - This is the most basic format of them all, even though
             all the format are actually very simple. The first four
             longwords are used for the width, height, xoffset, and
             yoffset respectively. The remaining data is the actual
             image. Simple. A diagram is shown below.

        +-------+--------+----------+----------+-----------+
        | Width | Height | x offset | y offset | image ... |
        +-------+--------+----------+----------+-----------+
         4 bytes 4 bytes   4 bytes    4 bytes    n bytes


    Packed Format - This format is nothing other than an encapsulated
            raw format. Essentially, the first longword contains
            to total number of raw brushes and the remainder of
            the file contains the raw brushes.

        +-------+-------------------------------------------+
        |       |+-----------+-----------+-----------+-----+|
        | total || raw brush | raw brush | raw brush | ... ||
        |       |+-----------+-----------+-----------+-----+|
        +-------+-------------------------------------------+
         4 bytes


    Font Format - The font format assumes that all 94 bitmap characters
              have the same width and height. The maximum width
              and height of any given character is 255 (still mighty
              big if you ask me). The first 2 unsigned characters
              represents the width and the height of the font
              respectively, and the remainder of the file is the actual
              bitmaps themselves. The figure below shows the layout.

        +-------+--------+---------------+
        | width | height | 94 images ... |
        +-------+--------+---------------+
         1 byte   1 byte



SAMPLE CODE:

#include <stdio.h>
#include <stdlib.h>

struct {
  unsigned long w;
  unsigned long h;
  long x_offset;
  long y_offset;
  unsigned char *image;
} raw;

struct {
  unsigned char w;
  unsigned char h;
  unsigned char alphabet;
} font;

struct raw *LoadRaw(char *filename)
{
  FILE *fd;
  struct raw *r;

  if ((fd = fopen(filename,"rb")) == 0) return 0;
  if ((r = calloc(1,sizeof(raw)) == 0) {
    fclose(fd);
    return 0;
  }
  fread(&r->w,sizeof(long),1,fd);
  fread(&r->h,sizeof(long),1,fd);
  fread(&r->x_offset,sizeof(long),1,fd);
  fread(&r->y_offset,sizeof(long),1,fd);
  if ((r->image = (unsigned char *)malloc(r->w * r->h)) == 0) {
    free(r);
    fclose(fd);
    return 0;
  }
  fread(r->image,sizeof(char),r->w*r->h,fd);
  fclose(fd);
  return r;
}

struct raw *LoadPCK(char *filename, unsigned long *t)
{
  FILE *fd;
  unsigned long i;
  struct raw *list;

  if ((fd = fopen(filename,"rb")) == 0) return 0;
  fread(t,sizeof(long),1,fd);
  if ((list = (struct raw *)calloc(*t,sizeof(struct raw))) == 0) {
    fclose(fd);
    return 0;
  }
  for(i=0;i<*t;i++) {
    fread(&list[i].w,sizeof(long),1,fd);
    fread(&list[i].h,sizeof(long),1,fd);
    fread(&list[i].x_offset,sizeof(long),1,fd);
    fread(&list[i].y_offset,sizeof(long),1,fd);
    if ((list[i].image = (unsigned char *)
            malloc(list[i].w * list[i].h) == 0) {
        for(i=0;i<*t;i++) if (list[i].image) free(list[i].image);
        free(list);
        fclose(fd);
        return 0;
    }
    fread(list[i].image,sizeof(char),list[i].w*list[i].h,fd);
  }
  fclose(fd);
  return list;
}

struct font *LoadFont(char *filename)
{
  FILE *fd;
  font *f;

  if ((fd = fopen(filename,"rb")) == 0) return 0;
  if ((f = (struct font *)calloc(1,sizeof(struct font)) == 0) {
    fclose(fd);
    return 0;
  }
  fread(&f->w,sizeof(char),1,fd);
  fread(&f->h,sizeof(char),1,fd);
  if ((f->alphabet = (unsigned char *)malloc(f->w * f->h * 94)) == 0) {
    free(f);
    fclose(fd);
    return 0;
  }
  fread(f->alphabet,sizeof(char),f->w*f->h*94,fd);
  return f;
}

The best way to access the individual characters in the alphabet is by
doing the method below.

    character = (char_val - '!') * fontwidth * fontheight

in other words...


unsigned char *Character(struct font *f, char c)
{
  if ((c < '!') || (c > '~')) return 0;
  return f->alphabet * ((c - '!') * f->w * f->h);
}



COMMAND LINE UTILS:

pcx2raw.exe - This program will also convert an entire PCX image into a giant
          raw brush. Note that during the conversion process the image
          looses the palette. To recover the palette use pcxpal.exe.
          To use pcx2raw just give a source file and destination file
          name. e.g.

            pcx2raw hello.pcx world.raw

pcxpal.exe  - This program extract the palette from a given pcx file. The
          palette file is stored as an RGB set. In other words, the
          first three unsigned bytes represents the first RGB set,
          the next three unsigned bytes is the next RGB set and so on.
          To use pcxpal just give a source file and a destination file
          name.

            pcxpal hello.pcx world.pal



CONCLUSION:

And there you have it, ways of using bcut to put graphics and/or animation
into your own program. well, actually you have to do the display part yourself;
i just provided and easier way of accessing the images. I hope you have many
uses for this program and that it does help you in doing something or other.
If you have any comments or suggestions or would like the source code, just
e-mail me at [e-mail] or at [e-mail]. Good
luck to you.